home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / interapplication comm / moreappleevents / aehelpers.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  10.5 KB  |  342 lines
  1. /*
  2.     File:        AEHelpers.h
  3.  
  4.     Contains:    Functions to help you when you are building and sending Apple events.
  5.  
  6.     Written by: Andy Bachorski
  7.         
  8.     Copyright:    Copyright © 1996-1999 by Apple Computer, Inc., All Rights Reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.                 7/21/1999    Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1
  20.                 
  21.  
  22. */
  23.  
  24. #if PRAGMA_ONCE
  25.     #pragma once
  26. #endif
  27.  
  28. #ifndef AEHELPERS
  29. #define AEHELPERS
  30.  
  31.  
  32. //••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
  33.  
  34. //    A private conditionals file to setup the build environment for this project.
  35.  
  36. #include "PrivateConditionals.h"
  37.  
  38.  
  39. //******************************************************************************
  40.  
  41. //    System includes
  42. #include <AERegistry.h>
  43. #include <AEObjects.h>
  44. #include <AEPackObject.h>
  45. #include <EPPC.h>
  46. #include <Gestalt.h>
  47. #include <Processes.h>
  48.  
  49.  
  50. //******************************************************************************
  51.  
  52. #ifdef __cplusplus
  53.     extern "C" {
  54. #endif
  55.  
  56.  
  57. //******************************************************************************
  58.  
  59. OSErr AEHMakeEventSelfTarget( AEEventClass eventClass,
  60.                               AEEventID eventID,
  61.                               AppleEvent *eventPtr );
  62. /*
  63.     Create and return an AppleEvent of the given class and ID. The event will be
  64.     targeted at the current process, with an AEAddressDesc of type
  65.     typeProcessSerialNumber.
  66.  
  67.     eventClass        input:    The class of the event to be created.
  68.     eventID            input:    The ID of the event to be created.
  69.     eventPtr        input:    Pointer to an AppleEvent where the
  70.                             event record will be returned.
  71.                     output:    The Apple event.
  72.     
  73.     RESULT CODES
  74.     ____________
  75.     noErr               0    No error    
  76.     memFullErr        -108    Not enough room in heap zone    
  77.     ____________
  78. */
  79. //******************************************************************************
  80.  
  81. pascal    OSErr    AEHMakeEventSignatureTarget( OSType targetType,
  82.                                              OSType targetCreator,
  83.                                              AEEventClass eventClass,
  84.                                              AEEventID eventID,
  85.                                              AppleEvent *theEvent );
  86. /*
  87.     Create and return an AppleEvent of the given class and ID. The event will be
  88.     targeted at the process specified by the target type and creator codes, 
  89.     with an AEAddressDesc of type typeProcessSerialNumber.
  90.  
  91.     targetType        input:    The file type of the process to be found.
  92.     targetCreator    input:    The creator type of the process to be found.
  93.     eventClass        input:    The class of the event to be created.
  94.     eventID            input:    The ID of the event to be created.
  95.     theEvent        input:    Pointer to an AppleEvent where the
  96.                             event record will be returned.
  97.                     output:    The Apple event.
  98.     
  99.     RESULT CODES
  100.     ____________
  101.     noErr               0    No error    
  102.     memFullErr        -108    Not enough room in heap zone    
  103.     procNotFound    –600    No eligible process with specified descriptor
  104.     ____________
  105. */
  106.  
  107. //******************************************************************************
  108.  
  109. pascal    OSErr    AEHMakeEventProcessTarget( const ProcessSerialNumberPtr psnPtr,
  110.                                            AEEventClass eventClass,
  111.                                            AEEventID eventID,
  112.                                            AppleEvent *theEvent );
  113. /*
  114.     Create and return an AppleEvent of the given class and ID. The event will be
  115.     targeted with the provided PSN.
  116.  
  117.     psnPtr            input:    Pointer to the PSN to target the event with.
  118.     eventClass        input:    The class of the event to be created.
  119.     eventID            input:    The ID of the event to be created.
  120.     theEvent        input:    Pointer to an AppleEvent where the
  121.                             event record will be returned.
  122.                     output:    The Apple event.
  123.     
  124.     RESULT CODES
  125.     ____________
  126.     noErr               0    No error    
  127.     memFullErr        -108    Not enough room in heap zone    
  128.     procNotFound    –600    No eligible process with specified descriptor
  129.     ____________
  130. */
  131.  
  132. //******************************************************************************
  133.  
  134. pascal    OSErr    AEHMakeEventTargetID( const TargetID *targetIDPtr,
  135.                                       AEEventClass eventClass,
  136.                                       AEEventID eventID,
  137.                                       AppleEvent *theEvent );
  138. /*
  139.     Create and return an AppleEvent of the given class and ID. The event will be
  140.     targeted with the provided TargetID.
  141.  
  142.     targetIDPtr        input:    Pointer to the TargetID to target the event with.
  143.     eventClass        input:    The class of the event to be created.
  144.     eventID            input:    The ID of the event to be created.
  145.     theEvent        input:    Pointer to an AppleEvent where the
  146.                             event record will be returned.
  147.                     output:    The Apple event.
  148.     
  149.     RESULT CODES
  150.     ____________
  151.     noErr               0    No error    
  152.     memFullErr        -108    Not enough room in heap zone    
  153.     procNotFound    –600    No eligible process with specified descriptor
  154.     ____________
  155. */
  156.  
  157. //******************************************************************************
  158.  
  159. pascal    OSErr    AEHSendEventReturnSInt16( const AEIdleUPP idleProcUPP,
  160.                                           const AppleEvent *theEvent,
  161.                                                 SInt16 *theValue );
  162. /*
  163.     Send the provided AppleEvent using the provided idle function.
  164.     Return a SInt16 (typeSmallInteger).
  165.  
  166.     idleProcUPP        input:    The idle function to use when sending the event.
  167.     theEvent        input:    The event to be sent.
  168.     theValue        output:    The value returned by the event.
  169.     
  170.     RESULT CODES
  171.     ____________
  172.     noErr               0    No error    
  173.     paramErr         -50    No idle function provided
  174.     
  175.     and any other error that can be returned by AESend or the handler
  176.     in the application that gets the event.
  177.     ____________
  178. */
  179.  
  180. //******************************************************************************
  181.  
  182. pascal    OSErr    AEHSendEventNoReturnValue( const AEIdleUPP idleProcUPP,
  183.                                            const AppleEvent *theEvent );
  184. /*
  185.     Send the provided AppleEvent using the provided idle function.
  186.     Will wait for a reply if an idle function is provided, but no result will be returned.
  187.  
  188.     idleProcUPP        input:    The idle function to use when sending the event.
  189.     theEvent        input:    The event to be sent.
  190.     
  191.     RESULT CODES
  192.     ____________
  193.     noErr               0    No error    
  194.     
  195.     and any other error that can be returned by AESend or the handler
  196.     in the application that gets the event.
  197.     ____________
  198. */
  199.  
  200. //******************************************************************************
  201.  
  202. pascal    OSErr    AEHGetHandlerError( const AppleEvent *reply );
  203. /*
  204.     Takes a reply event checks it for any errors that may have been returned
  205.     by the event handler. A simple function, in that it only returns the error
  206.     number. You can often also extract an error string and three other error
  207.     parameters from a reply event.
  208.     
  209.     Also see:
  210.         IM:IAC for details about returned error strings.
  211.         AppleScript developer release notes for info on the other error parameters.
  212.     
  213.     reply        input:    The reply event to be checked.
  214.  
  215.     RESULT CODES
  216.     ____________
  217.     noErr                    0    No error    
  218.     ????                    ??    Pretty much any error, depending on what the
  219.                                 event handler returns for it's errors.
  220. */
  221.  
  222. //******************************************************************************
  223.  
  224. OSErr AEHExtractClassAndID ( const AppleEvent *eventPtr,
  225.                              AEEventClass *eventClass,
  226.                              AEEventID *eventID );
  227. /*
  228.     Get the class and ID from an AppleEvent.
  229.  
  230.     eventPtr        input:    The event to get the class and ID from.
  231.     eventClass       output:    The event's class.
  232.     eventID           output:    The event's ID.
  233.     
  234.     RESULT CODES
  235.     ____________
  236.     noErr                        0    No error    
  237.     memFullErr                 -108    Not enough room in heap zone    
  238.     errAEDescNotFound         -1701    Descriptor record was not found    
  239.     errAENotAEDesc            -1704    Not a valid descriptor record    
  240.     errAEReplyNotArrived    -1718    Reply has not yet arrived    
  241. */    
  242.  
  243. //******************************************************************************
  244.  
  245. pascal    Boolean    AEHSimpleIdleFunction( EventRecord *event,
  246.                                        long *sleepTime,
  247.                                        RgnHandle *mouseRgn );
  248. /*
  249.     A very simple idle function. It simply ignors any event it receives,
  250.     returns 30 for the sleep time and nil for the mouse region.
  251.     
  252.     Your application should supply an idle function that handles any events it
  253.     might receive. This is especially important if your application has any windows.
  254.     
  255.     Also see:
  256.         IM:IAC for details about idle functions.
  257.         Pending Update Perils technote for more about handling low-level events.
  258. */    
  259.  
  260. //******************************************************************************
  261.  
  262. pascal    Boolean    GestaltAvailable( void );
  263. /*
  264.     Is the Gestalt trap present.
  265.     
  266.     RESULT CODES
  267.     ____________
  268.     true    Gestalt is present
  269.     false    It isn't
  270. */
  271.  
  272. //******************************************************************************
  273.  
  274. pascal    Boolean    HasAppleEvents( void );
  275. /*
  276.     Is the Apple Event Manager present.
  277.     
  278.     RESULT CODES
  279.     ____________
  280.     true    The Apple Event Manager is present
  281.     false    It isn't
  282. */
  283.  
  284. //******************************************************************************
  285.  
  286. pascal    Boolean    FinderCallsAEProcess( void );
  287. /*
  288.     Does the Finder call AEProcessAppleEvent when it receives an Apple event.
  289.     
  290.     RESULT CODES
  291.     ____________
  292.     true    Finder is version 7.1.3 or later, calls AEProcessAppleEvent,
  293.             and supports the full old Finder event suite.
  294.     false    The Finder supports a subset of the old Finder event suite.
  295.     
  296.     Use this routine together with FinderIsOSLCompliant to determine which
  297.     suite of events the Finder supports.
  298. */
  299.  
  300. //******************************************************************************
  301.  
  302. pascal    Boolean    FinderIsOSLCompliant( void );
  303. /*
  304.     Does the Finder uses the ObjectSupportLib to resolve objecs.
  305.         
  306.     RESULT CODES
  307.     ____________
  308.     true    Finder is version 7.5 or later, and supports the Standard event suite,
  309.             the new Finder event suite & a subset of the old Finder event suite.
  310.     false    See result of FinderCallsAEProcess.
  311.     
  312.     Support for the old Finder event suite is limited, with some events missing
  313.     and some events only partially supported. The subset of old Finder event
  314.     supported is not the same subset as the original Finder 7 supported.
  315.     
  316.     Use the new event suite, and avoid the old one, whenever possible. 
  317. */
  318.  
  319. //******************************************************************************
  320.  
  321. pascal    Boolean    FinderUsesIconFamily( void );
  322. /*
  323.     Does the Finder uses cIconFamily records or IconSuites.
  324.     
  325.     So far (as of Mac OS 8.1) only the Finder in Mac OS 8.0 requires the use of
  326.     IconSuites, rather than cIconFamily like the other Finders.  This test
  327.     lets us identify this odd Finder so we can special case Icon code.
  328.         
  329.     RESULT CODES
  330.     ____________
  331.     true    Finder uses cIconFamily.
  332.     false    Finder uses IconSuite.
  333. */
  334.  
  335. //******************************************************************************
  336.  
  337. #ifdef __cplusplus
  338. }
  339. #endif
  340.  
  341. #endif// AEHELPERS
  342.